home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu171.dms / pu171.adf / docs / NCOMM / Script.doc / Script.doc
Text File  |  1992-03-18  |  27KB  |  840 lines
  1. The NComm V2.0 scriptlanguage
  2. =============================
  3.  
  4. A scriptfile is an ASCII textfile that consists of different commands,
  5. separated by  one or more  linefeeds.  Edit the  scriptfiles with your
  6. favourite  editor.  Only  one  command is  allowed per line, but blank
  7. lines are also OK. A line can consist of blanks before the command and
  8. between parameters.  Comments can be added by entering a semicolon.  A
  9. label is marked with a colon as its last character, e.g. "quit:".  The
  10. script  commands  are case independent,  but strings within quotes are
  11. not.
  12.  
  13. Scripts  are mainly used to automate logons, or to companion you while
  14. you  are  online.   Scripts  can also perform more advanced functions,
  15. like  grabbing  mail  and perhaps posting it on another board (or even
  16. printing it!).  You set the limits...
  17.  
  18. One example  script and  one  Host-Mode script have been included with
  19. the NComm package.  Take a look at them if you don't understand how to
  20. use the commands.
  21.  
  22. Important:   The  filenames  specified in a scriptfile are relative to
  23. the   current   directory,   NOT   the  default  upload  and  download
  24. directories!
  25.  
  26. Quick-Index (strings within brackets are optional)
  27. --------------------------------------------------
  28.  
  29. ASCSEND "filename"         : Send a file to the serial port
  30. AUTODOWN ON|OFF            : Turn Zmodem auto-download on or off
  31. AUTOUP ON|OFF              : Turn Zmodem auto-upload on or off
  32. AUTOXFER ON|OFF            : Turn G&R commands on or off
  33. BEEP                       : Make an audible/visible/screentofront beep
  34. BREAK                      : Send a break to the host machine
  35. CAPTURE "filename"         : Capture serial input to a file
  36. CD "directory"             : Change current directory for "CLI" commands
  37. CHAIN "filename"           : Start another script
  38. CLEARVARS                  : Clear all variables
  39. CLI "command"              : Execute external command
  40. CLRSTACK                   : Clear the RETURN stack
  41. CONFIG "filename"          : Load another configuration file
  42. CONVERSE "in" "out"        : Wait for input, send output
  43. DELAY seconds              : Wait for specified number of seconds
  44. DIAL "boardname"[,"next"]  : Dial one or more entries in phonebook
  45. DIAL# "number"[,"next"]    : Dial one or more telephone numbers
  46. DLWHEN                     : Delete last WHEN command
  47. DORX "filename"            : Execute an ARexx command/script
  48. DOWNLOAD "filename"[,P]    : Download file [with protocol P]
  49. DTENTHS tenthseconds       : Delay for specified number of tenthseconds
  50. DUMP ["filename"]          : Dump list of variables [to optional file]
  51. DWHEN "string"             : Delete WHEN checking for "string"
  52. DWHENS                     : Delete all WHEN statements
  53. ECHO ON|OFF                : Enable/disable INPUT/ASCSEND/MSGSEND cmd echo
  54. END                        : Stop execution of script
  55. GOSUB subroutine           : Call a subroutine
  56. GOTO label                 : Jump to a label
  57. HANGUP                     : Hang up the phone
  58. IF <exp> THEN <command>    : Execute command if expression is TRUE
  59. INPUT $variable "stopchar" : Put serial-port input in variable, until stopchar
  60. LOADKEYS "filename"        : Load a new set of macrokeys
  61. LOADPHONE "filename"       : Load a new phonebook
  62. MENUSELECT "menu" item sub : Select an item/subitem from the menu
  63. MESSAGE "message"          : Display a message on the terminal
  64. MSGSEND "filename"         : Send a message to the serial port
  65. PADLINES ON|OFF            : Turn padding of blank lines off/on
  66. PALETTE                    : Open the palette requester
  67. PRINTER ON|OFF             : Turn the printer on or off
  68. QUIT                       : Exit NComm
  69. READVAR $variable          : Read a line from VARFILE into $variable
  70. REPEAT<->UNTIL <expression>: Perform a loop until expression is TRUE
  71. REDIAL ON|OFF              : Turn redial on or off
  72. REQUEST ON|OFF             : Turn system/NComm requesters on/off
  73. RESUME ON|OFF              : Turn Zmodem resume on or off
  74. RETURN                     : Returns from a sub-routine (see GOSUB)
  75. SEND "string"              : Send a string to the serial port
  76. SET $variable = "value"    : Assign value to $variable
  77. SIMPLEREQ "string"         : Display string in a simple requester
  78. TIMEOUT seconds [command]  : Sets timeout to seconds [and command at timeout]
  79. UPLOAD "filename"[,P]      : Upload file [with protocol P]
  80. VARFILE "filename"|CLOSE   : Open file for input/close file (see READVAR)
  81. WAIT "string"              : Waits for string to be received (see TIMEOUT)
  82. WHILE <exp> DO...ENDWHILE  : Perform loop if expression is TRUE (check first)
  83. WHEN "string" command      : Execute command when string is received
  84. WRITE "filename" "string"  : Write string to file
  85.  
  86. Summary of Script commands
  87. --------------------------
  88.  
  89.         ASCSEND
  90. Starts ASCII text send of the filename given. Example:
  91.  
  92. ASCSEND "df1:text/msg"
  93.  
  94. The  TIMEOUT command also concerns ASCSEND.  If ASCSEND is halted by a
  95. ^S  and  no  ^Q  has  been  received within the timelimit specified by
  96. TIMEOUT,  the  script  will  go on with the next command.  XON will be
  97. turned on before ASCSEND.
  98.  
  99. ----------------------------------------------------------------------
  100.  
  101.         AUTODOWN
  102. Turns Zmodem auto-download ON or OFF.
  103.  
  104. Example:
  105.  
  106. AUTODOWN ON      ;Turns Zmodem auto-download on
  107. AUTODOWN OFF     ;Turns Zmodem auto-download off
  108.  
  109. ----------------------------------------------------------------------
  110.  
  111.         AUTOUP
  112. Turns Zmodem auto-upload ON or OFF.
  113.  
  114. Example:
  115.  
  116. AUTOUP ON      ;Turns Zmodem auto-upload on
  117. AUTOUP OFF     ;Turns Zmodem auto-upload off
  118.  
  119. ----------------------------------------------------------------------
  120.  
  121.         AUTOXFER
  122. Turns G&R commands ON or OFF.
  123.  
  124. Example:
  125.  
  126. AUTOXFER ON      ;Turns G&R commands on
  127. AUTOXFER OFF     ;Turns G&R commands off
  128.  
  129. ----------------------------------------------------------------------
  130.  
  131.         BEEP
  132. Will  cause  an audible 'beep' of the terminal and / or will flash the
  133. screen  and / or will bring the screen to front, depending on what you
  134. have  configured  in  the  SCREEN  menu.   Nothing is sent through the
  135. serial port.
  136.  
  137. ----------------------------------------------------------------------
  138.  
  139.         BREAK
  140. Sends a break to the host machine. Equivalent to SEND "\l".
  141.  
  142. ----------------------------------------------------------------------
  143.  
  144.         CAPTURE
  145. Toggles ASCII capture on/off. Examples:
  146.  
  147. CAPTURE "filename"
  148. Will  open the capture file and turn on capture.  It will be opened in
  149. 'append mode' if the file exists...
  150.  
  151. CAPTURE SUS
  152. Will suspend capture.  Capture can be turned on again with the command
  153. CAPTURE ON
  154.  
  155. CAPTURE OFF
  156. Will  turn  capture off and close the file.  The file cannot be opened
  157. again with the CAPTURE ON command.
  158.  
  159. ----------------------------------------------------------------------
  160.  
  161.         CD
  162. Problems  occur  when  the "CD" command is used with the CLI function.
  163. The  "CD"  command  has  therefore  been  made a special function.  It
  164. simply  changes  the directory that is to be used for commands started
  165. with the "CLI" function.
  166.  
  167. Example:
  168.  
  169. CD "RAM:"       ;Will change the current working directory to 'RAM:'
  170.  
  171. ----------------------------------------------------------------------
  172.  
  173.         CHAIN
  174. Will start a new script.  The control will never return to the calling
  175. script.   This  is  useful  when  you need extremely long scripts that
  176. won't fit in memory.
  177.  
  178. Example:
  179.  
  180. CHAIN "NComm:ReadNews.script"
  181.  
  182. Note:   Variables  will  not  be deleted when using the CHAIN command.
  183. Use the command CLEARVARS if you want to delete all variables.
  184.  
  185. ----------------------------------------------------------------------
  186.  
  187.     CLEARVARS
  188. This command deletes all variables.
  189.  
  190. ----------------------------------------------------------------------
  191.  
  192.         CLI
  193. Will  execute  a program or a command.  The output from these programs
  194. and  commands  will  occur  in the NComm window.  This command will be
  195. relative to the directory you were standing in when you started NComm.
  196.  
  197. Please  note;  Current  Directory can not be set with the CLI command,
  198. probably  due  to  problems with the Amiga operating system.  The "CD"
  199. function must therefore be used for this purpose.
  200.  
  201. Examples:
  202.  
  203. CLI "dir dh0:comms"
  204. CLI "type ram:foo.bar"
  205. CLI "pkax ram:grabfile.arc"
  206.  
  207. ----------------------------------------------------------------------
  208.  
  209.         CLRSTACK
  210. This  command  clears  the  RETURN  stack,  i.e.   it  forgets  active
  211. subroutine  calls (gosubs).  The command is handy at error situations,
  212. when  you  wish to "jump out" of the program and start over again, for
  213. example in conjunction with TIMEOUT or WHEN commands.
  214.  
  215. ----------------------------------------------------------------------
  216.  
  217.         CONFIG
  218. Will read a new configuration file.  Example:
  219.  
  220. CONFIG "NComm:MBBS.config"
  221.  
  222. ----------------------------------------------------------------------
  223.  
  224.         CONVERSE
  225. Will wait for a prompt from the host machine and answer it.
  226.  
  227. Examples:
  228.  
  229. CONVERSE "Enter your name:" "Name\n"   ;Waits for 'Enter your name:'
  230. CONVERSE "enter your password:" "\p\n" ;Sends phonebook password + CR
  231. CONVERSE "Command:" "G\n"              ;Sends 'G' and newline
  232.  
  233. ----------------------------------------------------------------------
  234.  
  235.         DELAY
  236. The  script  program  will take a break.  The program will function as
  237. normal.
  238.  
  239. Examples:
  240.  
  241. DELAY 5                 ;Wait 5 seconds
  242. DELAY UNTIL 12:00       ;Wait until 12 o'clock.
  243.  
  244. ----------------------------------------------------------------------
  245.  
  246.         DIAL
  247. Will  dial  one  or  more  phonenumbers.  Can also dial entries in the
  248. phonebook.   If  you  choose  to  dial  phonenumbers,  use the command
  249. 'DIAL#'.   The  numbers must be placed within quotation marks.  If you
  250. choose to dial more than one number, the numbers can be separated by a
  251. comma.
  252.  
  253. Examples:
  254.  
  255. DIAL# "454143"
  256. DIAL# "380949", "493210", "454143"
  257.  
  258. Named  entries  in  the  phonebook  can  be  dialled by specifying the
  259. boardname within quotation marks.  You only have to specify the number
  260. of  letters  required  to  separate  the  board  from the others.  The
  261. name is not case sensitive.
  262.  
  263. Examples:
  264.  
  265. DIAL "AmigaBBS"
  266. DIAL "rode", "Mike's", "media"
  267. DIAL "Rodeløkka (M)BBS"
  268.  
  269. ----------------------------------------------------------------------
  270.  
  271.         DLWHEN
  272. Deletes  the last defined WHEN command.  Repeated usage will succesive
  273. delete the "previous" WHEN command.  See:  WHEN.
  274.  
  275. ----------------------------------------------------------------------
  276.  
  277.     DORX
  278. This command executes an ARexx command/script.
  279.  
  280. Example: DORX "ncomm:test_rx.ncomm"
  281.  
  282. ----------------------------------------------------------------------
  283.  
  284.         DOWNLOAD
  285. Will download a file from the host machine.  The protocol specified in
  286. the  TRANSFER  menu will be used as long as nothing else is specified.
  287. If you want to specify another protocol, enter a comma and a letter.
  288. The filename is "dummy" when using Zmodem.
  289.  
  290. X == Xmodem, Y == Ymodem, B == Ymodem-B, G == Ymodem-G, Z == Zmodem,
  291. K == Kermit, E == External XPR (as defined in config file),
  292. J == Jmodem, Q == QuickB
  293.  
  294. Examples:
  295.  
  296. DOWNLOAD "df1:junk"             ;Will use the default protocol
  297. DOWNLOAD "df0:trash",X          ;Will always use Xmodem
  298.  
  299. ----------------------------------------------------------------------
  300.  
  301.         DTENTHS
  302. This  is  a much more precise delay command, but only use this command
  303. when  this  accuracy is needed, since it will lock up the system.  The
  304. DTENTHS parameter is the number of tenth seconds to wait.
  305.  
  306. Examples:
  307.  
  308. DTENTHS 2       ;Wait 0.2 seconds
  309. DTENTHS 16      ;Wait 1.6 seconds
  310.  
  311. ----------------------------------------------------------------------
  312.  
  313.         DUMP
  314. Command  for debugging a script.  It dumps a list of all variables and
  315. what  they contain, on screen.  If you specify a filename, output will
  316. be appended to the file instead, and will not be shown on screen.
  317.  
  318. Example: DUMP "t:debug_info"
  319.  
  320. ----------------------------------------------------------------------
  321.         DWHENS
  322. Deletes a specific WHEN command. It should be followed by the string
  323. that you used for activating the WHEN command.
  324.  
  325. Example:
  326.     WHEN "abc" GOTO abc
  327.         WHEN "bcd" GOTO bcd
  328.         [...]
  329.         DWHEN "abc" ;remove "abc" when checking
  330.  
  331. ----------------------------------------------------------------------
  332.  
  333.         DWHENS
  334. Will disable all previously used WHEN commands. See: WHEN.
  335.  
  336. ----------------------------------------------------------------------
  337.  
  338.         ECHO
  339. This  command defines if characters read by the INPUT command shall be
  340. echoed.   ECHO ON should be used when input is read from a user in the
  341. other  end. ECHO OFF should be used when input is read from a Bulletin
  342. Board  System, or when the user is not supposed to see what he writes.
  343.  
  344. ECHO  should  be  turned  ON  if the functions ASCSEND and MSGSEND are
  345. supposed  to  echo text locally.  The output from the CLI command will
  346. be sent to the serial port if ECHO has been turned on.
  347.  
  348. ----------------------------------------------------------------------
  349.  
  350.         END
  351. Will  stop  the  execution  of the script.  This command is especially
  352. useful in front of subroutines.
  353.  
  354. Example:
  355.  
  356. WHEN "Read>" GOSUB next
  357. WAIT "No more unread."
  358. END
  359.  
  360. Next: SEND "\n"
  361.       MESSAGE "(Skipping to next unread)\n"
  362.       RETURN
  363.  
  364. ----------------------------------------------------------------------
  365.  
  366.         GOSUB
  367. Will  call  a  named subroutine.  Useful when you want to use the same
  368. command  many  times  within  a  script, or in connection with WHEN or
  369. TIMEOUT.   The  subroutine  is ended with 'RETURN', and the control is
  370. passed to the line following the GOSUB afterwards.
  371.  
  372. Example:
  373.  
  374. GOSUB myRoutine
  375. END
  376.  
  377. MyRoutine: MESSAGE "Fooo\n"
  378.            BEEP
  379.            RETURN
  380.  
  381. ----------------------------------------------------------------------
  382.  
  383.         GOTO
  384. Ever heard of this? Will jump to a named place in the script.
  385.  
  386. Example:
  387.  
  388. GOTO quit
  389. ...
  390. quit: CAPTURE OFF
  391.       HANGUP
  392.       END
  393.  
  394. NOTE:   Don't  use "LABEL:  GOTO LABEL" if you want an "endless" wait.
  395. This  will  steal  most  of  your machines CPU.  Use the DELAY or WAIT
  396. commands instead.
  397.  
  398. ----------------------------------------------------------------------
  399.  
  400.         HANGUP
  401. Will send the hangup string to the modem (or lower DTR if you have
  402. selected DTR hangup).
  403.  
  404. ----------------------------------------------------------------------
  405.  
  406.         IF <expression> THEN <operation>
  407.  
  408. It  should be obvious what this command does.  A valid expression can
  409. be either a comparison of two strings or a check for a file.  The
  410. exclamation mark ('!') works as a boolean 'NOT' operator.
  411.  
  412. String comparisons are performed with the "==" operator, which tests for
  413. case independent equality, i.e.  "foo" == "FOO" is TRUE;
  414. !"bar" == "yum" is TRUE (because of the '!' (NOT) operator)
  415.  
  416. EXISTS  checks  if a file exists.  The following are examples on valid
  417. IF commands:
  418.  
  419. SELECTFALSE  opens  up  a "Yes / No" requester and is TRUE if the user
  420. selected "No".
  421.  
  422. RING checks for a (hardware) RING signal.
  423.  
  424. CARRIER checks for (hardware) CARRIER detect.
  425.  
  426.         IF $password == "abcdef" THEN MESSAGE "Access granted\n"
  427.         IF !$password == "xyz" THEN GOTO KillUser
  428.         IF EXISTS "NComm:host.config" THEN CONFIG "NComm:host.config"
  429.         IF !EXISTS $file THEN SEND "File not found!\n"
  430.  
  431.         IF !SELECTFALSE "Slow modem?" THEN SET $baud = 300
  432.  
  433.         Loop: DELAY 1
  434.               IF RING THEN GOSUB Send_ATA
  435.               IF CARRIER THEN GOTO Connect
  436.               GOTO Loop
  437.  
  438. The whole command must be placed on a single line, including the 'THEN'
  439. part...
  440.  
  441. SEE ALSO: SET
  442.  
  443. ----------------------------------------------------------------------
  444.  
  445.         INPUT
  446. This  command  reads  input  from  the  serial port and places it in a
  447. variable  until  a  specific string has been received.  ^H (backspace)
  448. deletes  the  last  character,  ^U  deletes  the  whole  string.   The
  449. searchstring  will  not  be added to the variable.  Control characters
  450. will not be added.  Example:
  451.  
  452.         SEND "Enter your first name: "
  453.         INPUT $name "\r" ;Input will be placed in the variable 'name'
  454.                          ;until carriage return is received.
  455.  
  456. The  TIMEOUT  command  also  concerns  the INPUT command.  The timeout
  457. defines  how long INPUT shall wait for the terminating string ("\r" in
  458. the mentioned example).  Example:
  459.  
  460.         TIMEOUT 180 Goto BiBi
  461.         SEND "Enter a command: "
  462.         INPUT $cmd "\r"
  463.         ...
  464.  
  465. BiBi:   SEND "\n\nLooks like you fell asleep!!  Bye-bye!\n"
  466.         HANGUP
  467.         END
  468.  
  469. It is also possible to read a single character without having to
  470. wait for ENTER or other strings:
  471.  
  472.         INPUT $char ""
  473.  
  474. INPUT  can  both  be  used for reading input from a user in connection
  475. with  "Host  Mode",  or  grabbing pieces of text from a Bulletin Board
  476. System;
  477.  
  478.         WAIT "Bulletins have been updated: "
  479.         INPUT $bull " "
  480.  
  481. ----------------------------------------------------------------------
  482.  
  483.         LOADKEYS
  484. Will read a new macrokeys file.
  485.  
  486. Example:
  487.  
  488. LOADKEYS "NComm:dec.Keys"
  489.  
  490. ----------------------------------------------------------------------
  491.  
  492.         LOADPHONE
  493. Will read a new phonebook file.
  494.  
  495. Example:
  496.  
  497. LOADPHONE "NComm:dialdir.phone"
  498.  
  499. ----------------------------------------------------------------------
  500.  
  501.     MENUSELECT
  502. This command selects a function from the menu.
  503.  
  504. Example:
  505.     MENUSELECT SYSTEM 0     ;Open About Window
  506.         MENUSELECT TRANSFER 6 2 ;Selects KERMIT Change Directory
  507.  
  508. ----------------------------------------------------------------------
  509.  
  510.         MESSAGE
  511. Will  write  a  message  on  the  screen.  Nothing is sent through the
  512. serial port.  You may use all the conventions that are valid for
  513. macrokeys. Please refer to the NComm.doc.
  514.  
  515. Example:
  516.  
  517. MESSAGE "\fReading mail...\n"
  518. MESSAGE "Storing mail in file \"DF1:Mail.txt\"\n"
  519.  
  520. ----------------------------------------------------------------------
  521.  
  522.         MSGSEND
  523. Same  as the "message send" function in the TRANSFER menu, will upload
  524. a message.
  525.  
  526. Example:
  527.  
  528. MSGSEND "DF1:tekst/msg"
  529.  
  530. ----------------------------------------------------------------------
  531.  
  532.         PADLINES
  533. Turns padding of blank lines ON or OFF.
  534.  
  535. Example:
  536.  
  537. PADLINES ON      ;Will turn on padding of blank lines
  538. PADLINES OFF     ;Will turn off padding of blank lines
  539.  
  540. ----------------------------------------------------------------------
  541.  
  542.         PALETTE
  543. Will open the palette requester.
  544.  
  545. ----------------------------------------------------------------------
  546.  
  547.         PRINTER
  548. Turns the printer ON or OFF.
  549.  
  550. Example:
  551.  
  552. PRINTER ON      ;Will turn on the printer
  553. PRINTER OFF     ;Will turn off the printer
  554.  
  555. ----------------------------------------------------------------------
  556.  
  557.         QUIT
  558. Exits NComm.
  559.  
  560. ----------------------------------------------------------------------
  561.  
  562.     READVAR
  563. This command reads a line from the file defined by VARFILE and places
  564. the input in the variable name that follows. Please refer to VARFILE.
  565.  
  566. The variable will contain "EOF" after the read if the function hits an
  567. end of file mark...
  568.  
  569. ----------------------------------------------------------------------
  570.  
  571.         REDIAL
  572. Turns redial ON or OFF.
  573.  
  574. Example:
  575.  
  576. REDIAL ON      ;Will turn redial on
  577. REDIAL OFF     ;Will turn redial off
  578.  
  579. ----------------------------------------------------------------------
  580.  
  581.         REPEAT<->UNTIL <expression> ...
  582. This  command  performs what is situated between REPEAT and UNTIL.  If
  583. the  expression  is  FALSE/TRUE,  the procedure will be repeated.  See
  584. "IF...THEN" for a discussion of valid expressions. The command has the
  585. same restrictions as WHILE/ENDWHILE.
  586.  
  587. Example:
  588.  
  589. REPEAT
  590.         SEND "Enter command: "
  591.         INPUT $cmd "\r"
  592.         GOSUB DoCommand
  593. UNTIL $cmd == "quit"
  594.  
  595. ----------------------------------------------------------------------
  596.  
  597.         REQUEST
  598. This  function  is  used  when  the  scriptfile  is  run without human
  599. presence.   It  will  then  be  unpreferable  that  AmigaDOS puts up a
  600. requester  if  problems  occur (disk full, read / write error etc.) By
  601. turning request OFF, this is disabled.  Note: NComm will automatically
  602. overwrite existing files if request has been turned off
  603.  
  604. Example:
  605.  
  606. REQUEST OFF     ;Turns requesters off
  607. REQUEST ON      ;Will turn the requesters back on again
  608.  
  609. ----------------------------------------------------------------------
  610.  
  611.         RESUME
  612. Turns Zmodem resume ON or OFF.
  613.  
  614. Example:
  615.  
  616. RESUME ON      ;Turns Zmodem resume on
  617. RESUME OFF     ;Turns Zmodem resume off
  618.  
  619. ----------------------------------------------------------------------
  620.  
  621.         RETURN
  622. Returns from a subroutine. See GOSUB.
  623.  
  624. ----------------------------------------------------------------------
  625.  
  626.         SEND
  627. Sends a string to the host machine. You may use all the conventions
  628. that are valid for macrokeys. Please refer to the NComm.doc
  629.  
  630. Examples:
  631.  
  632. SEND "\n"       ;Linefeed
  633. SEND "Read\n"   ;'Read' plus a CR
  634. SEND "\m1^z"    ;Macro #1 plus a 'Control-Z'
  635. SEND "\p\n"     ;The password stored in the phonebook plus a CR
  636.  
  637. ----------------------------------------------------------------------
  638.  
  639.         SET
  640. This  command  is  used  for assigning values to variables.  Variables
  641. have  name  in  the form $name where 'name' starts with a letter.  The
  642. value  must be of type string, either a literal (with quotation marks)
  643. or another variable.
  644.  
  645. Examples:
  646.  
  647.         SET $name = "Daniel"
  648.         SEND $name
  649.  
  650.         SET $filename = "RAM:foo"
  651.         CAPTURE $filename
  652.  
  653.         SET $UserName = $name
  654.  
  655. Variables  can  be  used everywhere where strings are expected.  There
  656. are a few pre-defined variables available:
  657.  
  658.    $date contains the current date and time (READ ONLY).
  659.    $ncomm contains the current version number (READ ONLY).
  660.    $baud contains the current baud rate (Read/Write).
  661.    $length contains the current data length (Read/Write).
  662.    $parity contains the current parity (Read/Write).
  663.    $stopbits contains the current number of stopbits (Read/Write)
  664.    $charset contains the current character set (Read/Write).
  665.    $filereq opens up a filereq and returns the filename (READ ONLY).
  666.    $stringreq opens up a textreq and returns the string (READ ONLY).
  667.  
  668. It is also possible to concatenate several variables and/or literals;
  669.  
  670.         SEND $name"\n"
  671.         SET $directory = "NComm:files/"
  672.         INPUT $filename "\r"
  673.         UPLOAD $directory$filename
  674.  
  675.         SET $baud = "300" ;sets baud-rate to 300 baud
  676.         SEND $date"\n"    ;print current date and time
  677.  
  678.         SET $length = "7" ;7 data bits
  679.         SET $parity = "E" ;even parity
  680.         SET $charset = "IBN" ;set IBN character set
  681.  
  682. It is not valid referring to variables having no value assigned.
  683.  
  684. NOTE: You may use the pre-defined variable $FILEREQ for obtaining
  685. a filename.
  686.  
  687. Example:
  688.       SET $filename = $FILEREQ ;open filereq, put name in $filename
  689.       IF $filename != "" CONFIG $filename ;use the filename
  690.  
  691. Use the pre-defined variable $STRINGREQ if you want the user to
  692. type in a string.
  693.  
  694. Example:
  695.       SET $baud = $STRINGREQ ;set baud-rate to number entered by user
  696.  
  697. ----------------------------------------------------------------------
  698.  
  699.     SIMPLEREQ
  700. Use this command if you want to display text in a seperate requester.
  701.  
  702. Example: SIMPLEREQ "You selected: "$filename"\n"
  703.  
  704. ----------------------------------------------------------------------
  705.  
  706.         TIMEOUT
  707. This  command lets you configure how long NComm should wait in a WAIT,
  708. CONVERSE  or INPUT command.  Default timeout is 'forever', but this is
  709. not  preferable if the script is running without human assistance.  If
  710. the  host machine does not answer, it is reasonable to believe that it
  711. has  hung,  and a scriptfile should then automatically disconnect from
  712. the system.  The TIMEOUT command can be used in many ways.
  713.  
  714. Examples:
  715.  
  716. TIMEOUT 10
  717. Means  that  NComm shall wait a maximum of 10 seconds.  If no text has
  718. been  received  within  the  timelimit, NComm will go on with the next
  719. command.
  720.  
  721. TIMEOUT 10 SEND "\n"
  722. Specifies  that NComm is to wait a maximum of 10 seconds for each WAIT
  723. or  CONVERSE  command.   If  the  specified text has not been received
  724. within  10 seconds, NComm will send a linefeed to the host machine and
  725. will  continue  waiting  for  the  text.   NComm will continue sending
  726. linefeeds every 10th second until the host machine has answered.
  727.  
  728. TIMEOUT 0
  729. NComm is to go back to the default mode, i.e. wait forever.
  730.  
  731. Example of typical usage:
  732.  
  733. TIMEOUT 30 GOTO quit
  734. CONVERSE "Enter your name:" "Daniel Bloch\n"
  735. CONVERSE "Enter your password:" "gruff\n"
  736. CONVERSE "Command:" "GRAB\n"
  737. ...
  738. ...
  739. END
  740.  
  741. quit: MESSAGE "\n\nThe board has hung, call the SysOp!!!\n"
  742.       BEEP
  743.       HANGUP ;Hang up so that we won't get a shock when
  744.       END    ;the next phonebill arrives!
  745.  
  746. ----------------------------------------------------------------------
  747.  
  748.         UPLOAD
  749. Uploads  a  file to the host machine.  See the 'DOWNLOAD' function for
  750. the correct syntax.
  751.  
  752. ----------------------------------------------------------------------
  753.  
  754.     VARFILE
  755. This command opens a file for input. The file may later on be used
  756. for reading text into variables via the command READVAR.
  757.  
  758. Example:
  759.     VARFILE "ncomm:host/users/"$user ;open input file for reading
  760.         READVAR $passwd ;place first line of file in variable $passwd
  761.         READVAR $laston ;place second line of file in variable $laston
  762.         VARFILE CLOSE ;closes the input file
  763.  
  764.         MESSAGE "Hello "$user"! You were last on at "$laston"\n"
  765.  
  766. ----------------------------------------------------------------------
  767.  
  768.         WAIT
  769. Waits  for  a  special  text to be received.  Will wait forever if the
  770. TIMEOUT command has not been used.
  771.  
  772. Examples:
  773.  
  774. WAIT ""         ;Wait for 'anything'
  775. WAIT "\n"       ;Wait for a linefeed
  776. WAIT "Command:" ;Wait for 'Command:'
  777.  
  778. ----------------------------------------------------------------------
  779.  
  780.         WHILE <expression> DO ... ENDWHILE
  781. This  function  performs what is situated within DO and ENDWHILE until
  782. the expression is TRUE/FALSE.
  783.  
  784. Example:
  785.  
  786. SET $cmd = ""
  787. WHILE !$cmd == "quit" DO
  788.         SEND "Enter command: "
  789.         INPUT $cmd "\r"
  790.         GOSUB DoCommand
  791. ENDWHILE
  792.  
  793. It  is  not  valid  jumping out of a WHILE/ENDWHILE loop using GOTO or
  794. RETURN.   It  is  still  possible  to exit the loop using GOTO and the
  795. command   CLRSTACK.
  796.  
  797. ----------------------------------------------------------------------
  798.  
  799.         WHEN
  800. Defines what to do when a special text is received. The command is
  801. case sensitive.
  802.  
  803. Typical example:
  804.  
  805. WHEN "--more--" SEND " "
  806.  
  807. This  command  will  make  NComm  send  a  'blank'  line every time it
  808. receives the 'more' prompt from the host machine.  This is independent
  809. of  where  in the script  you reside.  It is possible to specify up to
  810. twenty such textstrings.
  811.  
  812. Example:
  813.  
  814. WHEN "--more--" SEND " "
  815. WHEN "NO CARRIER" END
  816. WHEN "Sysop is coming online!" GOSUB ShutUp
  817. WHEN "No more unread" GOTO Quit
  818.  
  819. Loop: CONVERSE "Command:" "\n"
  820.       GOTO loop
  821.  
  822. Quit: SEND "G;Y\n"
  823.       END
  824.  
  825. ShutUp: SEND "I'm not at home! You are chatting with a scriptfile!\n"
  826.         SEND "Send BIBI at the speed of light!!!\n\n"
  827.         RETURN
  828.  
  829. ----------------------------------------------------------------------
  830.  
  831.         WRITE
  832. This command writes a textstring to a file. If the file exists, the
  833. string will be appended to the file. Example:
  834.  
  835.         WRITE "NComm:host/log" "Logged in: "$username"\n"
  836.               |                |
  837.               Name of file     String
  838.  
  839. ----------------------------------------------------------------------
  840.